Developer CD Series 1998 August: Tool Chest/Dev.CD Aug 98 TC.toast/Tool Chest/Testing & Debugging/Virtual User/Virtual User Current Release/Examples/Example Libraries/UtilityTasks.vulib

Text File | 1998-06-04 | 20.4 KB | 587 lines | [TEXT/MPS ]

#
#    File:        UtilityTasks.vulib
#
#    Contains:    contains utility tasks for any scripts. Use Mark menu to
#                reach the desired task. The tasks are commented on what they do.
#
#    Written by:    P Nagarajan
#
#    Copyright:    © 1991-1996 by Apple Computer, Inc., all rights reserved.
#
#    Change History (most recent first):
#
#         <8>    2/28/96        CMW            Heavily modified FindFile to not use hardcoded ords,
#                                        removed selection of "More Choices" button, and
#                                        rearranged actions.
#         <8>    960227        JCU            Modified FindFile to reflect ordinality change of popups.
#                8/14/92        DGG            Modified CloseAllWindows and OpenOneWindow tasks.
#         <7>     7/1/92        DGG            Included modified RestartTarget task and twitching
#                                        tasks, closeAllWindows task and reformatted
#                                        existing tasks.
#         <6>     8/26/91    Rick        Marked new tasks
#         <5>     8/19/91    Rick        Fix LaunchAppInSystem7
#         <4>     8/19/91    Rick        Fix timing in LaunchAppInSystem7() task
#         <3>     8/19/91    Rick        Add FindWindowWithNoItems for 1.1 release
#         <2>     8/13/91    Rick        fixed OpenOneWindow to account for 7.0 Desktop window
#                   1/7/91    naga        creation
#
#    To Do:
#

(************************************************************************************
* Task CheckForAlertWindow(overrideAlerts, messagePrint)
*    Handles alert dialogs with 'OK' and 'Cancel' buttons.
*    if overrideAlerts is true then select 'OK' else 'Cancel' is selected
************************************************************************************)
task CheckForAlertWindow(overrideAlerts := false, messagePrint := true)
begin
    if (match [button w:[window ord:1 style:dialog] t:'OK']!)
    begin
        textMessages := collect[staticText w:[window ord:1 style:dialog]]!;
        if messagePrint
        begin
            println "### Dismissing dialog -- static text message follows:";
            for each singleMessage in textMessages
                println " ∂t",singleMessage.t;
        end;
        if overrideAlerts
            select [button t:'OK' w:[window ord:1 style:dialog]]!;
        else
            select [button t:'Cancel' w:[window ord:1 style:dialog]]!;
    end;#if dialog appeared
end;#CheckForAlertWindow

(************************************************************************************
* Task DismissConfirmDialog()
*    Handles alert dialogs with "No" buttons or any button beginning with "Don"
*    buttons.  Will simply click on these labeled buttons.
************************************************************************************)
task DismissConfirmDialog()
begin
    if (match [window o:1 s:dialog])
    begin
        match [staticText t:?theText w:[window o:1]];
        if ((theText ~= /Save≈/) or (theText ~= /Do you want to save≈/))
            if (match [button t:"No"])
                select [button t:"No"];
            else if (match [button t:/Don≈/])
                select [button t:/Don≈/];
    end;
end;

(************************************************************************************
* Task CloseAllWindows()
*    Will attempt to close all current windows.  First it will look for dialogs or
*    movable modals and try to close them, then it will close windows until there are
*    no more windows to close.
************************************************************************************)
task CloseAllWindows()
begin
    totalWindows := collect [window];
    match [application t:?currentApp];

    for each singleWindow in totalWindows do
    begin
        if (singleWindow.s = dialog) or (singleWindow.s = movablemodal)
        begin
            if match [button t:'OK' w:1]!
            begin
                select [button t:'OK' w:1]!;
                if not (currentApp = "Finder")
                    DismissConfirmDialog();
            end;
            else if match [button t:'Cancel' w:1]!
            begin
                select [button t:'Cancel' w:1]!;
                if not (currentApp = "Finder")
                    DismissConfirmDialog();
            end;
        end;
        else if not (                                      # skip 7.0 Finder desktop window
                    match [system v:/7.≈/]!                # system 7    ?
                    and currentApp = "Finder"    # finder ?
                    and match [window t:"Desktop" o:1]!     # Desktop window ?
                    )
        begin
            if (singleWindow.c)
                close [window o:1];
            else if match [menuItem m:"File" t:/Close≈/ e:true ]
                select [menuItem m:"File" t:/Close≈/ e:true ];
            else
                println "### Unable to close window: ", singleWindow.t;
            if scriptError()
                println "### Unable to close window: ", singleWindow.t;
            if not (currentApp = "Finder")
                DismissConfirmDialog();
        end;
    end;
end;

(************************************************************************************
* Task FindFile(fileName)
*    This task will find a file using the "Find…" menu item in the File menu, using
*    name contains and on all disks at once.  It assumes that the Finder is currently
*    active.
************************************************************************************)
task FindFile(fileName := "", FindBy := "Name", MatchType := "Contains", Disk := "on all disks")
begin

    foundFile := true;

    select [menuItem t:"Find…" m:[menu o:2]];
    Wait(2);

    while (match [window t:/Find≈/]!).o <> 1
    begin
        if (match [window o:1]!).c = true
            close [window o:1]!;
        else
            select [button t:"Ok" w:[window o:1]];
    end;

    while match [button t:"Fewer Choices" w:[window t:/Find≈/ o:1]]!
    begin
        select [button t:"Fewer Choices" w:[window t:/Find≈/ o:1]]!;
        Wait(1);
    end;

    # There is a problem in the Find dialog where the "Find By" popup has all
    #    of its menuitems removed if a "Fewer Choices" button is selected.
    # The menuitems are not recomputed until another popup is selected.
    # So we select the location popup and THEN the Find By.

    select [menuItem t:Disk m:[popup w:1]];            #select [menuItem t:Disk m:[popup o:18]];        # On all disks
    select [menuItem t:FindBy m:[popup w:1]];                                                        # Name
    type k:{ fileName };
    select [menuItem t:MatchType m:[popup w:1]];    #select [menuItem t:MatchType m:[popup o:6]];    # Is

    select [button t:"Find" w:[window t:/Find≈/ o:1]];    # Click Find

    stillSearching := true;
    # A search may not find anything or it may take a long time.  This is one way
    # of dealing with the different outcomes.
    while stillSearching
    begin
        Wait(2);
        thisWindow := match [window o:1];
        if (thisWindow.s = dialog)
            stillSearching := false;
        else if (thisWindow.t ~= /Find≈/)
            stillSearching := true;
        else
            stillSearching := false;
    end;

    if (thisWindow.s = dialog)
    begin
        if not (match [staticText t:/“{fileName}” was found on the≈/ w:[window s:dialog o:1]])
            foundFile := false;
        select [button t:"Ok" w:[window o:1]];
    end;

    return foundFile;
end;

(************************************************************************************
* Task FindObjectInWindow( atX, atY )
*    this task moves the mouse on to a particular object of interest. Very useful
*    to select files in "view by name" mode in Finder.
*    this assumes that the file/icon/object you want to select is on the frontmost
*    window with coordinates (atX, atY) relative to the window's origin
************************************************************************************)
task FindObjectInWindow(atX, atY)
begin
    match [window o:1 r:?rect]!;
    iconX := rect[1] + atX;
    iconY := rect[2] + atY;
    move a:{iconX, iconY};
end; #FindObjectInWindow

(************************************************************************************
* Task FindWindowWithNoItems()
*    Returns a full descriptor of a window with an empty content list
*    If no such window is found, the empty descriptor is returned
************************************************************************************)
task FindWindowWithNoItems()
begin
    allWindows := collect[window];                # Gat a list of all windows
    for each W in all_Window do                    # Search for an empty window
        if Card W.k = 0                            # Is this one empty?
            return W;                            # If so, return its descriptor

    #    If none found, return empty descriptor
    return [];
end; #FindWindowWithNoItems

(************************************************************************************
* Task GracefulExit( msg )
*    Exits VU after printing the supplied 'msg' along with script execution time
************************************************************************************)
task GracefulExit(msg := '')
begin
    println msg;
    if (TypeOf( global startTime ) <> 'undefined')
        println "## started at  : ", global startTime;
    println "## finished at : ", match [time];
    exit;
end; #GracefulExit

(************************************************************************************
* Task NumberOfWindows()
*    Returns the total number of open windows
*    In system 7.0's Finder the Desktop is considered a window. This task
*    ignores that window and returns the number of regular open windows.
************************************************************************************)
task NumberOfWindows()
begin
    allWindows := collect [window];
    match [application t:?appName]!;
    if not (global System7)
         return card allWindows;
    else if global System7 and (appName ~= /≈Finder≈/ )
        return card allWindows - 1;
end; #NumberOfWindows

(************************************************************************************
* Task OpenOneWindow()
*    This task leaves one window open in the Finder.  It performs in a round about
*    way, first closing all windows and then trying to open one.  This task uses
*    the CloseAllWindows task.
************************************************************************************)
task OpenOneWindow()
begin
    success := true;

    numWindows := NumberOfWindows();
    if ( numWindows = 1 )
        return success;
    else if ( numWindows > 1)
        CloseAllWindows();

    numWindows := NumberOfWindows();
    if ( numWindows = 0 )
    begin
        if (match [menuItem t:'Open' m:'File' e:true]!)
        begin
            select [menuItem t:'Open' m:'File']!;
            success := NumberOfWindows();
        end; #if a window can be opened thru' the menu
        else do
            success := false;
    end; #no windows currently
    else do #could not close all windows
    begin
        match [window t:?topWindowTitle o:1];
        if (topWindowTitle <> "Desktop")
            success := false;
    end;
    return success;
end; #OpenOneWindow

(************************************************************************************
* Task RunningSystemSeven()
*    Is the target running System 7.0.x?
************************************************************************************)
task RunningSystemSeven()
begin
    match [system v:?sysVersion];
    return ((sysVersion ~= /7≈/) or (sysVersion ~= /≈-7≈/));     # 7.x system software
                                                                # on the target
end; #RunningSystemSeven

(************************************************************************************
* Task TwitchAppInSystem6( appName, twitchWait )
*    This will select a currently running application in System 6 by "twitching" the
*    application's name in the Apple menu. The application needs to be currently
*    running!  Also, it is assumed that MultiFinder is running on the target!
*************************************************************************************)
task TwitchAppInSystem6(appName := "Finder", twitchWait := 1)
begin
    match [application t:?frontApp]!;
    if not (frontApp ~= /≈{appName}≈/)
    begin
        if match [menuItem t:/≈{appName}≈/ m:[menu o:1]]
            select [menuItem t:/≈{appName}≈/ m:[menu o:1]];
        Wait(twitchWait);
        match [application t:?frontApp]!;
        if not (frontApp ~= /≈{appName}≈/)
        begin
            println "### Failed to twitch to {appName}.";
            return false;
        end;
    end;
    return true;
end;

(************************************************************************************
* Task TwitchAppInSystem7( appName, twitchWait )
*    This will select a currently running application in System 7 by "twitching" the
*    menu item in the right most menu.  The application needs to be currently running!
*************************************************************************************)
task TwitchAppInSystem7(appName := "Finder", twitchWait := 1)
begin
    match [application t:?frontApp]!;
    if not (frontApp ~= /≈{appName}≈/)
    begin
        numberOfMenus := card collect [menu];
        if match [menuItem t:/≈{appName}≈/ m:[menu o:numberOfMenus]]
            select [menuItem t:/≈{appName}≈/ m:[menu o:numberOfMenus]];
        Wait(twitchWait);
        match [application t:?frontApp]!;
        if not (frontApp ~= /≈{appName}≈/)
        begin
            println "### Failed to twitch to {appName}.";
            return false;
        end;
    end;
    println "# Twitched to {appName}.";
    return true;
end;

(************************************************************************************
* Task TwitchApp( appName, twitchWait )
*    This will select a currently running application in either System 6 or 7 by
*    "twitching" app icon or appropriate the menu item in the right most menu.  The
*    application needs to be currently running!
*************************************************************************************)
task TwitchApp(appName := "Finder", twitchWait := 1)
begin
    if (RunningSystemSeven())
        return TwitchAppInSystem7(appName, twitchWait);
    else
        return TwitchAppInSystem6(appName, twitchWait);
end;

(************************************************************************************
* Task LaunchAppInSystem6( appName, launchWait )
*    Check for app running and/or attempt to get there by:
*    double-clicking the topmost file (in View by Name) in the frontmost window
*    in Finder. ( Intended for use under System 6.0.x )
*    launchWait is the number of seconds to wait before checking for successful
*    launch of the application.
************************************************************************************)
task LaunchAppInSystem6( appName := "", launchWait := 4 )
begin
    match [application t:?frontApp]!;
    if (not (frontApp ~= /≈{appName}≈/))
    begin
        if not (TwitchAppInSystem6(appName))
        begin
            if (not OpenOneWindow())
            begin
                println "### Could not launch {appName}";
                return false;
            end;
            select [menuItem t:'by Name' m:'View'];
            All_Scrollbars := collect [ scrollbar w:1 ];
            for each sb in All_Scrollbars
                if( sb.r[2] < 32 )
                    Scroll sb a:{ 0, 1 };
            FindObjectInWindow( 9, 46);#first file
            DoubleClick;
            Wait(launchWait);
            match [application t:?frontApp]!;
            if not (frontApp ~= /≈{appName}≈/)
            begin
                println "### Failed to launch {appName}";
                return false;
            end;
        end;
    end;
    println "### Launched {appName}";
    return true;
end; #LaunchAppInSystem6

(************************************************************************************
* Task LaunchAppInSystem7( appName, launchWait, closeWindow, CDEV )
*    Check for app running and/or attempt to get there by:
*    Using Finder's Find command to select the App, then using the open command.
*    ( This works only under System 7.0 )
*    launchWait is the number of seconds to wait before checking for successful
*    launch of the application.
************************************************************************************)
task LaunchAppInSystem7( appName := "", launchWait := 6, closeWindow := true,
                        CDEV := false )
begin
    if (not CDEV)
        match [application t:?frontApp]!;
    else
        match [window t:?frontApp o:1]!;

    if (not (frontApp = appName))
    begin
        if (not TwitchAppInSystem7(appName))
        begin
            TwitchAppInSystem7();                # Get to Finder!
            if (not OpenOneWindow())
            begin
                println "### Could not launch {appName}";
                return false;
            end;

            if (FindFile( appName, "Name", "Contains" ))
            begin
                if closeWindow
                    pressKey k:{optionKey};
                select [menuItem t:"Open" m:[menu o:2]];
                if closeWindow
                    releaseKey k:{optionKey};
                Wait(launchWait);

                if (not CDEV)
                begin
                    match[application t:?frontApp]!;
                    if not (frontApp ~= /≈{appName}≈/)
                    begin
                        println "### Failed to launch {appName}";
                        return false;
                    end;
                end;
                else
                begin
                    match [window t:?frontCDEV o:1];
                    if not (frontCDEV ~= /≈{appName}≈/)
                    begin
                        println "### Failed to launch {appName}";
                        return false;
                    end;
                end;
            end;
            else
            begin
                println "### Failed to find {appName}";
                println "### Failed to launch {appName}";
                return false;
            end;
        end;
    end;
    println "### Launched {appName}";
    return true;
end; #LaunchAppInSystem7

(************************************************************************************
* Task LaunchApp( appName, launchWait, closeWindow, CDEV)
*    This will launch the specified application after determining whether System 6 or
*    System 7 is being used on the target.
*************************************************************************************)
task LaunchApp(appName := "", launchWait := 6, closeWindow := true, CDEV := false )
begin
    if (RunningSystemSeven())
        return LaunchAppInSystem7(appName, launchWait, closeWindow, CDEV);
    else
        return LaunchAppInSystem6(appName, launchWait);
end;

(************************************************************************************
* Task RestartTarget(timeToRestart := 15)
*    This task will restart the current target machine.  It assumes that Finder is
*    the current application.  The timeToRestart parameter specifies the amount of
*    time to wait until the Virtual User tries to reacquire the target.
************************************************************************************)
task RestartTarget(timeToRestart := 15)
begin
    # The following are error codes that are returned by acquireTarget and releaseTarget
    noError := 0;
    targetNotFound := 3; #error codes returned by acquireTarget/releaseTarget
    targetFailure := 1;   #error codes returned by acquireTarget/releaseTarget

    # Get the target name and zone through unification.
    match [target t:?targetName z:?targetZone];

    # Do restart via menu selection.
    select [menuItem t:'Restart' m:'Special']!;

    # Do a release target _before_ the target restarts; this is essential for VU to
    #    realize that the the target under control has been lost. This then allows us
    #    to do a fresh acquireTarget.
    result := ReleaseTarget();

     if (result <> targetFailure)    # Released okay!
    begin
        (*
         * Do a small wait to allow machine to boot.
         * This step is not really required since we are going to keep trying to
         * acquireTarget until it's found.  This step allows us to lessen network
         * traffic.
         *)
        Wait(timeToRestart);

        # Do an acquire with the same old target name and zone address.
        result := AcquireTarget(targetName, targetZone);

        while (result = targetNotFound)    # Keep trying until target is found or
        begin                                #    some other error is reported.
            result := AcquireTarget(targetName, targetZone);
        end;
        if (result = noError)
        begin
            (*
             * Need to wait until all inits get loaded.
             * The following wait via menu match is not enough since the menu
             * match succeeds before the finder really comes up visually.
             * the caller of this restart task may have to do additional wait
             * after this task call using a better heuristic based on the
             * context(may be window match?)
             *)
            while not match[menu];

            return noError;
        end;    # if (result = noError)
        else
            return result;
    end;    # if (result <> targetFailure)
    return result;    # Error!  Couldn't release target!
end;    #RestartTarget

(************************************************************************************
* Task ThrowItemToTrash(printAnyError := true, overrideAlerts := false)
*    This task trashes a specified object in Finder.
*     Assumes that the mouse is already positioned on the item to be trashed
*     and that the trash can is positioned on the main screen at (-40,-40) relative to
*     the lower right corner.
*     Arguements: 'printAnyError' can be used to suppress error messages and
*                'overrideAlerts' can be used to trash despite alerts.
************************************************************************************)
task ThrowItemToTrash(printAnyError := true, overrideAlerts := false)
begin
    PressMouse;
    match [screen r:?rect m:true]!;
    if rect
    begin
        trash_x := rect[3] - 40; #assumes trash can is at its usual location
        trash_y := rect[4] - 40; #ie., (40,40) off form the right bottom corner of main screen
        old_mouse_speed := mouseSpeed(5); #slow the mouse down
        move a:{trash_x, trash_y};
        #move a:{472, 301};#trash can on a SE
        mouseSpeed(old_mouse_speed); #reset the mouse speed to what it was before
        ReleaseMouse;
        CheckForAlertWindow(overrideAlerts);
        if match [menuItem t:'Empty Trash' m:'Special' e:true]!
            select [menuItem t:'Empty Trash' m:'Special']!;
        else
        begin
            if printAnyError
                println "### Empty Trash menu item not enabled, could not trash…";
            return false;
        end;
    end;#if unified correctly
    else
    begin
        if printAnyError
            println "### Unable to find trash can, could not trash…";
        return false;
    end;
    return true;
end; #ThrowItemToTrash

(************************************************************************************
* Task UseKeyboardEquivalent( alias )
*    Do Menu command using key equivalent
************************************************************************************)
task UseKeyboardEquivalent(alias)
begin
    pressKey k:{ commandKey };
    type k:{ alias };
    releaseKey k:{ commandKey };
end; #UseKeyboardEquivalent